home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / turbovis / dlgds411.zip / SCRIPT.DOC < prev    next >
Text File  |  1993-08-07  |  13KB  |  311 lines
  1.  
  2. This file serves to document the script file as well as the conversion
  3. programs supplied with Dialog Design.
  4.  
  5. CONVERSION PROGRAM CALLING SEQUENCE
  6.  
  7. For source generating conversion programs, Dialog Design uses the
  8. following calling sequence:
  9.  
  10.   progname.exe  <scriptname>  <outfilename> <errorfilename>
  11.  
  12. Where <scriptname> is the script input filename, <outfilename> is the
  13. name of the file the source code is to be written to, and <errorfilename>
  14. is a file to which errors are written.  In operation, Dialog Design
  15. first writes the script file and then calls the program as above.  If the
  16. exitcode is non-zero, the error file is then read and the error displayed.
  17. Both the script and error files are then deleted.
  18.  
  19. In the implementations supplied, <errorfilename> is made optional and if
  20. omitted, error output comes to the console.  This allows the conversion
  21. programs to be run from DOS as well as from within Dialog Design--an aid
  22. in debugging.
  23.  
  24. The calling sequence for the resource conversion programs is slightly
  25. different:
  26.  
  27.   progname.exe <scriptname> <resource filename> <resource ID> <errorfilename>
  28.  
  29. where an additional parameter for the resource ID string has been added.
  30. Before calling a resource conversion program, Dialog Design checks to see
  31. if the resource filename exists.  If it does, it then checks to see if it's
  32. actually an EXE file or a resource file of the appropriate type (C++ or
  33. Pascal).  Hence the conversion program does not have to make these checks.
  34. However, the conversion program is responsible for making a backup of the
  35. old file if that's desirable.
  36.  
  37.  
  38. READSCPT.PAS
  39.  
  40. READSCPT.PAS compiles into a Pascal unit which reads the script files output
  41. by Dialog Design.  It's used for all three Pascal conversion programs
  42. supplied.  If you decide to write your own conversion programs, you can
  43. probably use this unit without change.
  44.  
  45. In brief, READSCPT reads through the script file storing the information
  46. for the dialog and its controls in variant records (type ScriptRec).  The
  47. dialog itself has a record called Dialog and the control records are
  48. inserted in a TCollection named, ScriptColl.  Thus, once the script file is
  49. read, all the data is available for processing by the rest of the program.
  50.  
  51.  
  52. READSCPT.CPP
  53.  
  54. READSCPT.CPP and READSCPT.H similarly form a module for reading the script
  55. file.  It's used by all the supplied C++ conversion programs and can
  56. probably be used without change for any modified conversion programs.
  57.  
  58. READSCPT defines an abstract struct (ViewObj) to serve as a base object
  59. for later descendants.  In addition to defining fields common to all
  60. controls, three abstract code writing methods are also defined.
  61.  
  62. Also defined are script reading descendants of ViewObj for the dialog itself
  63. and each of the controls.  These descendants contain fields special to each
  64. control and have a contructor which reads it's portion of the script file
  65. and fills in the fields.
  66.  
  67. The final descendants of ViewObj are defined in the source code or resource
  68. generator module where the codewriting methods are fleshed out to do
  69. whatever is appropriate.
  70.  
  71. READSCPT requires that a function ( getKind() ) be defined in the codewriting
  72. section.  This function takes a single enum parameter which defines the basic
  73. type of control (button, inputline, etc.).  The return should be an instance
  74. of the final descendant of that basic type.  See any of the C++ conversion
  75. programs for an example of getKind().
  76.  
  77. As the script file is read, each ViewObj descendant is inserted in a
  78. TNSCollection named ScriptColl and the dialog itself is stored in Dialog.
  79.  
  80.  
  81.  
  82. SPECIAL CONTROL EXAMPLE
  83.  
  84. The supplied conversion files can be easily modified to accommodate specially
  85. derived controls.  PASSRC1 and CPPSRC1 already have an example of such a
  86. modification.  If you take a look at the demo, OPBUTTON.DLG, you'll see that
  87. it contains a special option button with a pointer name, POptionButton
  88. (TOptionButton would have been a better name in C++).  The constructor call
  89. for POptionButton is quite different from that of normal TButtons requiring
  90. two word parameters (here named PBOptions and PBEventMask) in addition to
  91. the normal TRect.  In addition, POptionButton also requires a special field
  92. in the dialog's transfer data record (here called AOptions).  This extra
  93. information has been entered in the control's 'Extra' dialog.
  94.  
  95. Both PASSRC1 and CPPSRC1 have a few extra lines of code added to be on the
  96. lookout for POptionButton and generate the proper constructor call for it.
  97.  
  98.  
  99. SCRIPT FILE
  100.  
  101. While looking over the documentation for the script file, it would be
  102. helpful for you to print out a sample script file as well as the Interface
  103. part of READSCPT.PAS (for Pascal users) or READSCPT.H (for C++ users).
  104.  
  105. The script file generated by Dialog Design is an ASCII file which consists
  106. entirely (except for the first item) of only two types of tokens, decimal
  107. numbers and double quoted strings.  Not much to be said about decimal
  108. numbers, but here's a few facts about the strings:
  109.  
  110.    "This is a string\n"
  111.  
  112.    There's three different escape sequences a string may contain:
  113.      '\n'    a newline
  114.      '\"'    a double quote within the string
  115.      '\\'    a backslash within the string
  116.  
  117.    A '+' immediately following the quote is used to indicate concatenation
  118.    with the next string.  In this manner strings of up to 255 characters
  119.    can be output with 80 or so characters per line.
  120.      "This is considered"+
  121.      "one string."
  122.  
  123. The layout for the script file consists of variable length records for the
  124. dialog itself followed by similar records for each control in the dialog,
  125. something like:
  126.  
  127.              |-----------------|
  128.              |  Version        |
  129.              |-----------------|
  130.              |  Reserved       |
  131.              |=================|
  132.              |  Fixed Part     |   -|
  133.              |-----------------|    |__ Dialog
  134.              |  Variable Part  |   -|
  135.              |=================|
  136.              |  Fixed Part     |   -|
  137.              |-----------------|    |__ Control
  138.              |  Variable Part  |   -|
  139.              |=================|
  140.                      .
  141.                      .
  142.              |=================|
  143.              |  Fixed Part     |   -|
  144.              |-----------------|    |__ Control
  145.              |  Variable Part  |   -|
  146.              |=================|
  147.              |  -1             |
  148.              |-----------------|
  149.  
  150. The script file starts off with "SCRIPT1" (but without the quotes in this
  151. case) followed by a newline.  This serves to verify the file IS a script
  152. file and supplies the version number.  A reserved section comes next--
  153. a single quoted string and a single number. Following this are the records
  154. for the dialog, and for each of the controls in the dialog.  The controls
  155. appear in Tab order (reverse Z order) except for TLabel's, THistory's,
  156. and attached TScrollBar's.  Labels and Historys immediately follow the
  157. control to which they're attached and attached ScrollBars immediately
  158. precede the control they're attached to.
  159.  
  160. The last control is followed with -1 to indicate there are no more.
  161.  
  162. The record for each control ( and the dialog itself) consists of a fixed
  163. part and a variable part.  The fixed part is identical for each type of
  164. control (although sometimes fields are blank).  The variable part varies
  165. with each type of control.
  166.  
  167. FIXED PART
  168.  
  169. Here's the order and contents of the fixed part:
  170.  
  171.    Name          Type              Example or comment
  172.  
  173.    Kind          RecType           Identifies the control type
  174.    BaseObj       string            "TInputLine"  (the basic type)
  175.    Obj           string            "PMyInputLine"/"TMyInputLine" (the
  176.                                    Pointer Name/Class Name)
  177.    X1,Y1,X2,Y2   Integer           The TRect
  178.    DefOptns      word              Default options for the control
  179.    Optns         word              The options as specified
  180.    DefEvMsk      word              Default EventMask for the control
  181.    EvMsk         word              The eventmask as specified
  182.